<!DOCTYPE html>
<html lang="en"><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <meta charset="utf-8">
    <meta name="generator" content="rustdoc">
    <title>Rust Documentation</title>

    <link rel="stylesheet" type="text/css" href="Rust%20Documentation_files/rust.css">

    <link rel="shortcut icon" href="http://www.rust-lang.org/favicon.ico">
<link href="Rust%20Documentation_files/css.css" rel="stylesheet" type="text/css">

<link href="Rust%20Documentation_files/sbi.css" rel="stylesheet" type="text/css" id="sbi-style"></head>
<body>
    <!--[if lte IE 8]>
    <div class="warning">
        This old browser is unsupported and will most likely display funky
        things.
    </div>
    <![endif]-->

    <div id="versioninfo">
  <img src="Rust%20Documentation_files/rust-logo-32x32-blk.png" alt="" height="32" width="32"><br>
  <span class="white-sticker"><a href="http://rust-lang.org/">Rust</a> 0.11.0-pre-nightly</span><br>
  <a href="http://github.com/mozilla/rust/commit/022a7b3cfb8014f79c79ba85a8273d16cda6e423" class="hash white-sticker">022a7b3c</a>
</div>


    <h1 class="title">Rust Documentation</h1>
    <nav id="TOC"><ul></ul>
<li><a href="#creating-documentation">1 Creating Documentation</a><ul></ul></li>
<li><a href="#using-the-documentation">2 Using the Documentation</a><ul></ul></li>
<li><a href="#testing-the-documentation">3 Testing the Documentation</a><ul>
<li><a href="#defining-tests">3.1 Defining tests</a><ul></ul></li>
<li><a href="#running-tests-%28advanced%29">3.2 Running tests (advanced)</a><ul></ul></li></ul></li>
<li><a href="#standalone-markdown-files">4 Standalone Markdown files</a><ul></ul></li></ul></nav><p><code>rustdoc</code> is the built-in tool for generating documentation. It integrates
with the compiler to provide accurate hyperlinking between usage of types and
their documentation. Furthermore, by not using a separate parser, it will
never reject your valid Rust code.</p>

<h1 id="creating-documentation" class="section-header"><a href="#creating-documentation">1 Creating Documentation</a></h1>
<p>Documenting Rust APIs is quite simple. To document a given item, we have "doc
comments":</p>
<pre class="rust "><span class="comment">// the "link" crate attribute is currently required for rustdoc, but normally
// isn't needed.
</span><span class="attribute">#<span class="op">!</span>[<span class="ident">crate_id</span> <span class="op">=</span> <span class="string">"universe"</span>]</span>
<span class="attribute">#<span class="op">!</span>[<span class="ident">crate_type</span><span class="op">=</span><span class="string">"lib"</span>]</span>

<span class="doccomment">//! Tools for dealing with universes (this is a doc comment, and is shown on
</span><span class="doccomment">//! the crate index page. The ! makes it apply to the parent of the comment,
</span><span class="doccomment">//! rather than what follows).
</span>
<span class="doccomment">/// Widgets are very common (this is a doc comment, and will show up on
</span><span class="doccomment">/// Widget's documentation).
</span><span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">Widget</span> {
    <span class="doccomment">/// All widgets have a purpose (this is a doc comment, and will show up
</span>    <span class="doccomment">/// the field's documentation).
</span>    <span class="ident">purpose</span>: <span class="ident">StrBuf</span>,
    <span class="doccomment">/// Humans are not allowed to understand some widgets
</span>    <span class="ident">understandable</span>: <span class="ident">bool</span>
}

<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">recalibrate</span>() {
    <span class="doccomment">//! Recalibrate a pesky universe (this is also a doc comment, like above,
</span>    <span class="doccomment">//! the documentation will be applied to the *parent* item, so
</span>    <span class="doccomment">//! `recalibrate`).
</span><span class="comment">    /* ... */
</span>}
</pre>

<p>Doc comments are markdown, and are currently parsed with the
<a href="https://github.com/vmg/sundown/">sundown</a> library. rustdoc does not yet do any fanciness such as
referencing other items inline, like javadoc's <code>@see</code>. One exception to this
is that the first paragraph will be used as the "summary" of an item in the
generated documentation:</p>
<pre class="rust "><span class="doccomment">/// A whizbang. Does stuff. (this line is the summary)
</span><span class="doccomment">///
</span><span class="doccomment">/// Whizbangs are ...
</span><span class="kw">struct</span> <span class="ident">Whizbang</span>;
</pre>

<p>To generate the docs, run <code>rustdoc universe.rs</code>. By default, it generates a
directory called <code>doc</code>, with the documentation for <code>universe</code> being in
<code>doc/universe/index.html</code>. If you are using other crates with <code>extern crate</code>,
rustdoc will even link to them when you use their types, as long as their
documentation has already been generated by a previous run of rustdoc, or the
crate advertises that its documentation is hosted at a given URL.</p>

<p>The generated output can be controlled with the <code>doc</code> crate attribute, which
is how the above advertisement works. An example from the <code>libstd</code>
documentation:</p>
<pre class="rust "><span class="attribute">#[<span class="ident">doc</span>(<span class="ident">html_logo_url</span> <span class="op">=</span> <span class="string">"http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png"</span>,
      <span class="ident">html_favicon_url</span> <span class="op">=</span> <span class="string">"http://www.rust-lang.org/favicon.ico"</span>,
      <span class="ident">html_root_url</span> <span class="op">=</span> <span class="string">"http://static.rust-lang.org/doc/master"</span>)]</span>;
</pre>

<p>The <code>html_root_url</code> is the prefix that rustdoc will apply to any references to
that crate's types etc.</p>

<p>rustdoc can also generate JSON, for consumption by other tools, with
<code>rustdoc --output-format json</code>, and also consume already-generated JSON with
<code>rustdoc --input-format json</code>.</p>

<h1 id="using-the-documentation" class="section-header"><a href="#using-the-documentation">2 Using the Documentation</a></h1>
<p>The web pages generated by rustdoc present the same logical hierarchy that one
writes a library with. Every kind of item (function, struct, etc) has its own
color, and one can always click on a colored type to jump to its
documentation. There is a search bar at the top, which is powered by some
JavaScript and a statically-generated search index. No special web server is
required for the search.</p>

<h1 id="testing-the-documentation" class="section-header"><a href="#testing-the-documentation">3 Testing the Documentation</a></h1>
<p><code>rustdoc</code> has support for testing code examples which appear in the
documentation. This is helpful for keeping code examples up to date with the
source code.</p>

<p>To test documentation, the <code>--test</code> argument is passed to rustdoc:</p>

<pre><code class="language-{.notrust}">rustdoc --test crate.rs</code></pre>

<h2 id="defining-tests" class="section-header"><a href="#defining-tests">3.1 Defining tests</a></h2>
<p>Rust documentation currently uses the markdown format, and rustdoc treats all
code blocks as testable-by-default. In order to not run a test over a block of
code, the <code>ignore</code> string can be added to the three-backtick form of markdown
code block.</p>

<pre><code class="language-notrust">```
// This is a testable code block
```

```ignore
// This is not a testable code block
```

    // This is a testable code block (4-space indent)</code></pre>

<p>You can specify that the test's execution should fail with the <code>should_fail</code>
directive.</p>

<pre><code class="language-notrust">```should_fail
// This code block is expected to generate a failure when run
```</code></pre>

<p>You can specify that the code block should be compiled but not run with the
<code>no_run</code> directive.</p>

<pre><code class="language-notrust">```no_run
// This code will be compiled but not executed
```</code></pre>

<p>Rustdoc also supplies some extra sugar for helping with some tedious
documentation examples. If a line is prefixed with <code>#</code>, then the line
will not show up in the HTML documentation, but it will be used when
testing the code block (NB. the space after the <code>#</code> is required, so
that one can still write things like <code>#[deriving(Eq)]</code>).</p>

<pre><code class="language-notrust">```
#&nbsp;// showing 'fib' in this documentation would just be tedious and detracts from
#&nbsp;// what's actually being documented.
#&nbsp;fn fib(n: int) { n + 2 }

spawn(proc() { fib(200); })
```</code></pre>

<p>The documentation online would look like <code>spawn(proc() { fib(200); })</code>, but when
testing this code, the <code>fib</code> function will be included (so it can compile).</p>

<h2 id="running-tests-(advanced)" class="section-header"><a href="#running-tests-%28advanced%29">3.2 Running tests (advanced)</a></h2>
<p>Running tests often requires some special configuration to filter tests, find
libraries, or try running ignored examples. The testing framework that rustdoc
uses is build on crate <code>test</code>, which is also used when you compile crates with
rustc's <code>--test</code> flag. Extra arguments can be passed to rustdoc's test harness
with the <code>--test-args</code> flag.</p>

<pre><code class="language-{.notrust}">$ rustdoc --test lib.rs --test-args 'foo'

$ rustdoc --test lib.rs --test-args '--help'</code></pre>

<p>When testing a library, code examples will often show how functions are used,
and this code often requires <code>use</code>-ing paths from the crate. To accommodate this,
rustdoc will implicitly add <code>extern crate &lt;crate&gt;;</code> where <code>&lt;crate&gt;</code> is the name of
the crate being tested to the top of each code example. This means that rustdoc
must be able to find a compiled version of the library crate being tested. Extra
search paths may be added via the <code>-L</code> flag to <code>rustdoc</code>.</p>

<h1 id="standalone-markdown-files" class="section-header"><a href="#standalone-markdown-files">4 Standalone Markdown files</a></h1>
<p>As well as Rust crates, rustdoc supports rendering pure Markdown files
into HTML and testing the code snippets from them. A Markdown file is
detected by a <code>.md</code> or <code>.markdown</code> extension.</p>

<p>There are 4 options to modify the output that Rustdoc creates.</p>

<ul>
<li><code>--markdown-css PATH</code>: adds a <code>&lt;link rel="stylesheet"&gt;</code> tag pointing to <code>PATH</code>.</li>
<li><code>--markdown-in-header FILE</code>: includes the contents of <code>FILE</code> at the
end of the <code>&lt;head&gt;...&lt;/head&gt;</code> section.</li>
<li><code>--markdown-before-content FILE</code>: includes the contents of <code>FILE</code>
directly after <code>&lt;body&gt;</code>, before the rendered content (including the
title).</li>
<li><code>--markdown-after-content FILE</code>: includes the contents of <code>FILE</code>
directly before <code>&lt;/body&gt;</code>, after all the rendered content.</li>
</ul>

<p>All of these can be specified multiple times, and they are output in
the order in which they are specified. The first line of the file must
be the title, prefixed with <code>%</code> (e.g. this page has <code>% Rust
Documentation</code> on the first line).</p>

<p>Like with a Rust crate, the <code>--test</code> argument will run the code
examples to check they compile, and obeys any <code>--test-args</code> flags. The
tests are named after the last <code>#</code> heading.</p>

    <footer><p>
Copyright © 2011-2014 The Rust Project Developers. Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>
or the <a href="http://opensource.org/licenses/MIT">MIT license</a>, at your option.
</p><p>
This file may not be copied, modified, or distributed except according to those terms.
</p></footer>



<div style="left: 0px; top: 0px; position: absolute; width: 29px; height: 27px; border: medium none; margin: 0px; padding: 0px; z-index: 2147483647; display: none;" class="sbi_search" id="sbi_camera_button"></div></body></html>